home *** CD-ROM | disk | FTP | other *** search
/ Amiga Tools 4 / Amiga Tools 4.iso / tools / internet-tools / connect-line / cl / devkit / docs / cl_text.doc < prev    next >
Encoding:
Text File  |  1995-09-01  |  13.2 KB  |  507 lines
  1. TABLE OF CONTENTS
  2.  
  3. cl_text.library/--background--
  4. cl_text.library/CLTXT_CloseCatalog
  5. cl_text.library/CLTXT_FormatDate
  6. cl_text.library/CLTXT_GetLanguageByDomain
  7. cl_text.library/CLTXT_GetString
  8. cl_text.library/CLTXT_MakeFile
  9. cl_text.library/CLTXT_OpenCatalog
  10. cl_text.library/CLTXT_OpenLocale
  11. cl_text.library/CLTXT_PrintfA
  12. cl_text.library/CLTXT_Replace
  13. cl_text.library/CLTXT_ReplaceAll
  14. cl_text.library/CLTXT_SPrintfA
  15. cl_text.library/--background--                 cl_text.library/--background--
  16.  
  17.    PURPOSE
  18.    The purpose of cl_text.library is to provide support for online
  19.    text output. It supports automatic language selection and
  20.    and has a versatile token replacement ability.
  21.  
  22.    CONNECTLINE LANGUAGES
  23.    The "cl_text.library" deals with it's internal set of languages
  24.    and text catalogs different from locale.library. The languages
  25.    are configured with a special preference editor (CL-TEXT-PREFS).
  26.    Every language setting consists of a few prefs entries and a set
  27.    of texts. The prefs currently consist of a reference language
  28.    and a workbench locale setting to use for the given language.
  29.    The reference language is used as a fallback if a given text
  30.    is not definied in the current language.
  31.  
  32.    Connectline Languages are accessed by name. Unknown languages
  33.    will automatically cause fallback to the default language.
  34.  
  35.    LOCALE SUPPORT
  36.    The library contains a few functions to support the functionality
  37.    of "locale.library", e.g. language specific number output and
  38.    date format. Also provided is a function to obtain a locale
  39.    pointer by connectline language name.
  40.  
  41.    TOKENS
  42.    "cl_text.library" supports a token replacement ability for
  43.    text files. Both builtin and application specific tokens
  44.    are supported.
  45.  
  46.    Tokens generally have the format
  47.  
  48.        $(tokenanme{optional-data})
  49.  
  50.    Valid examples for tokens are
  51.  
  52.        $(BOLD)
  53.        $(ENV{USERNAME})
  54.  
  55.  
  56.    BUILTIN TOKENS
  57.    Various tokens are implemented internally and can be used
  58.    everytime.
  59.  
  60.    $(DATE{fmt})  Insert current date with locale.library's FormatDate()
  61.                  (e.g. "$(DATE{%c})")
  62.    $(ENV{name})  Insert value of ENV variable (e.g. "$(ENV{USERNAME})")
  63.    $(FILE{name}) Insert file (max. 1024 chars)
  64.    $(FF)          Insert FormFeed (^L, 0x0c)
  65.    $(BELL)          Insert Bell (^G, 0x07)
  66.    $(BOLD)       Insert ANSI bold sequence
  67.    $(ITALIC)      Insert ANSI italic sequence
  68.    $(UNDERLINE)  Insert ANSI underline sequence
  69.    $(NORMAL)     Insert ANSI normal sequence
  70.    $(COL{num})   Insert ANSI color select sequence (e.g. "$(COL{1})")
  71.    $(BCOL0{num}} Insert ANSI background color select sequence
  72.  
  73.    EXTERNAL TOKENS
  74.    External tokens may be used to customize text output for special
  75.    applications. From the user's side, external tokens are no way different
  76.    from internal ones. However, the programmer providing external
  77.    tokens must specify them prior usage.
  78.  
  79.    External tokens are specified via an array of CLTXT_TokEnts:
  80.  
  81.      typedef struct CLTXT_TokEntry {
  82.        char *name;        // Name of token (UPPER CASE ONLY!)
  83.         ULONG type;        // Replacement type
  84.         APTR data;        // Data
  85.      };
  86.  
  87.    "type" may take different values depending on the type of "data":
  88.  
  89.       CLTXT_RT_STRING 0    Insert Data as a string (max. 1024 chars)
  90.       CLTXT_RT_INTEGER 1      Insert Data with %lD
  91.       CLTXT_RT_UNSIGNED 2    Insert Data with %lU
  92.       CLTXT_RT_HOOK 3        Call Hook
  93.                            (a0 = Hook, a1 = STRPTR to token data,
  94.                             a2 = STRPTR to buffer (must be zero-terminated, m
  95. ax. 1024 chars!))
  96.       CLTXT_RT_FILE 4        Data is file to include (max. 1024 chars!)
  97.  
  98. cl_text.library/CLTXT_CloseCatalog         cl_text.library/CLTXT_CloseCatalog
  99.  
  100.    NAME
  101.    CLTXT_CloseCatalog -- close a CL catalog (V2)
  102.                      
  103.  
  104.    SYNOPSIS
  105.    void CLTXT_CloseCatalog( clcatalog );
  106.                                A0
  107.  
  108.    void CLTXT_CloseCatalog( APTR );
  109.  
  110.    FUNCTION
  111.    Closes a catalog opened by CLTXT_OpenCatalog(). Note that
  112.    catalogs are cached until a memory flush.
  113.  
  114.    INPUTS
  115.    clcatalog -- catalog to close. Passing NULL is ignored.
  116.  
  117.    RESULT
  118.    None.
  119.  
  120.    EXAMPLE
  121.  
  122.    NOTES
  123.  
  124.    BUGS
  125.    None known.
  126.  
  127.    SEE ALSO
  128.    CLTXT_OpenCatalog(), CLTXT_GetString()
  129.  
  130. cl_text.library/CLTXT_FormatDate             cl_text.library/CLTXT_FormatDate
  131.  
  132.    NAME
  133.    CLTXT_FormatDate -- sprintf()-like interface to FormatDate()
  134.  
  135.    SYNOPSIS
  136.    CLTXT_FormatDate( locale, buffer, format, datestamp );
  137.                        A0      A1      A2       A3
  138.  
  139.    void CLTXT_FormatDate( struct Locale *, STRPTR, STRPTR, struct DateStamp *
  140.  );
  141.  
  142.    FUNCTION
  143.    calls locale.library/FormatDate() in a sprintf() like
  144.    manner.
  145.  
  146.    INPUTS
  147.    locale -- Locale to use. May be NULL.
  148.    buffer -- buffer to write to.
  149.    format -- formating string.
  150.    datestamp -- datestamp to use.
  151.  
  152.    RESULT
  153.    None.
  154.  
  155.    EXAMPLE
  156.  
  157.    NOTES
  158.  
  159.    BUGS
  160.    None known.
  161.  
  162.    SEE ALSO
  163.    locale.library/FormatDate(), CLTXT_PrintfA(), dos.library/DateStamp()
  164.  
  165. cl_text.library/CLTXT_GetLanguageByDomainxt.library/CLTXT_GetLanguageByDomain
  166.  
  167.    NAME
  168.    CLTXT_GetLanguageByDomain -- get langauge by domain adresse (V2)
  169.                      
  170.  
  171.    SYNOPSIS
  172.    langname = CLTXT_GetLanguageByDomain( domainadr );
  173.    D9                                       A0
  174.  
  175.    STRPTR CLTXT_GetLanguageByDomain( STRPTR );
  176.  
  177.    FUNCTION
  178.    Returns the language set for domain adresse "domainadr".
  179.    Returns the default language if no preference match is found.
  180.  
  181.    INPUTS
  182.    domainadr -- Domain address to parse.
  183.  
  184.    RESULT
  185.    langname -- pointer to language associated with "domainadr".
  186.  
  187.    EXAMPLE
  188.  
  189.    NOTES
  190.  
  191.    BUGS
  192.    None known.
  193.  
  194.    SEE ALSO
  195.  
  196. cl_text.library/CLTXT_GetString               cl_text.library/CLTXT_GetString
  197.  
  198.    NAME
  199.    CLTXT_GetString -- get a string from a CL catalog (V2)
  200.                      
  201.  
  202.    SYNOPSIS
  203.    STRPTR CLTXT_GetString( clcatalog, stringid, defstring );
  204.                                A0        A1        A2
  205.  
  206.    STRPTR CLTXT_GetString( APTR, STRPTR, STRPTR );
  207.  
  208.    FUNCTION
  209.    Returns a string from a CL catalog. If the string is not found,
  210.    or the catalog pointer is NULL, defstring is returned.
  211.  
  212.    INPUTS
  213.    clcatalog -- catalog. May be NULL.
  214.    stringid -- string ID of the string to find. Case insensitive.
  215.    defstring -- default string to return if clcatalog is NULL
  216.                 or the string is not found.
  217.  
  218.    RESULT
  219.    None.
  220.  
  221.    EXAMPLE
  222.  
  223.    NOTES
  224.    Do never ever modify a string returned by this function!
  225.  
  226.    BUGS
  227.    None known.
  228.  
  229.    SEE ALSO
  230.    CLTXT_OpenCatalog(), CLTXT_GetString()
  231.  
  232. cl_text.library/CLTXT_MakeFile                 cl_text.library/CLTXT_MakeFile
  233.  
  234.    NAME
  235.    CLTXT_MakeFile -- create a connectline text file with automatic
  236.                      langauge selection and token replacement.
  237.  
  238.    SYNOPSIS
  239.    error = CLTXT_MakeFile( cllangname, textid, tofilename, tokents )
  240.    D0                          A0        A1       A2          A3
  241.  
  242.    APTR CLTXT_MakeFile( STRPTR, STRPTR, STRPTR, struct  );
  243.  
  244.    FUNCTION
  245.    This is the big one: Given a language and a textid, it
  246.    creates a parsed output file with replaced macros et al.
  247.    Will fall back to the reference langauge or system default
  248.    langauge if the text is not avaible within the given
  249.    langauge set.
  250.  
  251.    INPUTS
  252.    cllangname -- language to use.
  253.    textid -- ID of text to create (e.g. "Login")
  254.    tofilename -- name of output file. If this string is EMPTY (not NULL!),
  255.                  it will automatically be filled with a temporary
  256.                  file name.
  257.    tokens -- external token entries. This is an array
  258.              terminated by an entry with a NULL name field.
  259.  
  260.    RESULT
  261.    error -- either 0 for succes or a negative value indicating an
  262.             error.
  263.  
  264.    EXAMPLE
  265.  
  266.    NOTES
  267.  
  268.    BUGS
  269.    None known.
  270.  
  271.    SEE ALSO
  272.    CLTXT_Replace()
  273.  
  274. cl_text.library/CLTXT_OpenCatalog           cl_text.library/CLTXT_OpenCatalog
  275.  
  276.    NAME
  277.    CLTXT_OpenCatalog -- open a CL catalog (V2)
  278.                      
  279.  
  280.    SYNOPSIS
  281.    clcatalog = CLTXT_OpenCatalog( cllangname, catalog )
  282.    D0                             A0         A1
  283.  
  284.    APTR CLTXT_OpenCatalog( STRPTR, STRPTR );
  285.  
  286.    FUNCTION
  287.    This function opens a CL catalog. CL catalogs are specialized
  288.    text files which contain tokens designating text strings.
  289.    This is somewhat comparable to locale's catalogs, but CL
  290.    catalogs are parsed at run time.
  291.  
  292.    The format of CL Catalogs is:
  293.  
  294.    ##stringid
  295.    text (may contain standard C escaping)
  296.  
  297.    for example:
  298.  
  299.    ##MSG_UNKNOWN_USER
  300.    User %s unbekannt!\n
  301.  
  302.    INPUTS
  303.    cllangname -- language to use.
  304.    catalog -- name of catalog.
  305.  
  306.    RESULT
  307.    catalog -- Pointer to (private) Catalog handle or NULL upon error.
  308.               Secondary result code is placed in IoErr()
  309.  
  310.    EXAMPLE
  311.     APTR cat;
  312.     cat = CLTXT_OpenCatalog( "Deutsch", "CLMSortin.cat" );
  313.     Printf( CLTXT_GetString( cat, "MSG_UNKNOWN_USER", "User %s unknown." ), u
  314. ser );
  315.     CLTXT_CloseCatalog( cat );
  316.  
  317.    NOTES
  318.  
  319.    BUGS
  320.    Stringids are limited to 63 chars, strings to 4095 chars.
  321.  
  322.    SEE ALSO
  323.    CLTXT_CloseCatalog(), CLTXT_GetString()
  324.  
  325. cl_text.library/CLTXT_OpenLocale             cl_text.library/CLTXT_OpenLocale
  326.  
  327.    NAME
  328.    CLTXT_OpenLocale -- open Locale by Connectline language name
  329.  
  330.    SYNOPSIS
  331.    locale = CLTXT_OpenLocale( cllangname )
  332.    D0                             A0
  333.  
  334.    struct Locale *CLTXT_OpenLocale( STRPTR );
  335.  
  336.    FUNCTION
  337.    Opens the Locale belonging to cllangname. Will automatically
  338.    fall back to the system's default locale.
  339.  
  340.    INPUTS
  341.    cllangname -- Connectline language name (don't mess up with
  342.                  locale languages)
  343.  
  344.    RESULT
  345.    locale -- wanted locale. Remember to CloseLocale() it
  346.              yourself.
  347.  
  348.    EXAMPLE
  349.  
  350.    NOTES
  351.  
  352.    BUGS
  353.    None known.
  354.  
  355.    SEE ALSO
  356.    locale.library/OpenLocale(), locale.library/CloseLocale()
  357.  
  358. cl_text.library/CLTXT_PrintfA                   cl_text.library/CLTXT_PrintfA
  359.  
  360.   NAME
  361.    CLTXT_PrintfA -- printf()-like interface to FormatString()
  362.    CLTXT_Printf -- varargs stub
  363.  
  364.   SYNOPSIS
  365.    nextdata = CLTXT_PrintfA( locale, format, args );
  366.    D0                          A0      A1     A2
  367.  
  368.    APTR CLTXT_PrintfA( struct Locale *, STRPTR, APTR );
  369.    APTR CLTXT_Printf( struct Locale *, STRPTR, ... );
  370.  
  371.   FUNCTION
  372.    calls locale.library/FormatString() in a printf() like
  373.    manner. The string will first be formatted, then processed
  374.    by CLTXT_ReplaceAll() and finally be printed.
  375.  
  376.   INPUTS
  377.    locale -- Locale to use. May be NULL.
  378.    format -- formating string
  379.    args -- args to format into string
  380.  
  381.   RESULT
  382.    nextdata -- points after last used element of args
  383.  
  384.   EXAMPLE
  385.  
  386.   NOTES
  387.  
  388.   BUGS
  389.    None known.
  390.  
  391.   SEE ALSO
  392.    locale.library/FormatString(), CLTXT_SPrintfA(),
  393.    dos.library/FPutC()
  394.  
  395. cl_text.library/CLTXT_Replace                   cl_text.library/CLTXT_Replace
  396.  
  397.    NAME
  398.    CLTXT_Replace -- token replacement.
  399.  
  400.    SYNOPSIS
  401.    replen = CLTXT_Replace( locale, token, buffer, tokents );
  402.    D0                         A0         A1     A2      A3
  403.  
  404.    APTR CLTXT_Replace( struct Locale *, STRPTR, STRPTR, CLTXT_TokEntry * );
  405.  
  406.    FUNCTION
  407.    This function replaces the token by it's value. Both
  408.    internal tokens and external token extensions are
  409.    recognized.
  410.  
  411.    INPUTS
  412.    locale -- locale to use (necessary for internal tokens)
  413.    token  -- token to replace
  414.    buffer -- buffer to hold token data.
  415.    tokens -- external token entries. This is an array
  416.              terminated by an entry with a NULL name field.
  417.                  
  418.    RESULT
  419.    replen -- replacement length or 0 if token couldn't be found.
  420.  
  421.    EXAMPLE
  422.  
  423.    NOTES
  424.    This is mainly a low level function to support other
  425.    cl_text.library functions.
  426.  
  427.    BUGS
  428.    None known.
  429.  
  430.    SEE ALSO
  431.    CLTXT_MakeText()
  432.  
  433. cl_text.library/CLTXT_ReplaceAll             cl_text.library/CLTXT_ReplaceAll
  434.  
  435.   NAME
  436.     CLTXT_ReplaceAll -- token replacement for strings.
  437.  
  438.   SYNOPSIS
  439.     len = CLTXT_ReplaceAll( locale, src, dst, dstlen, tokents );
  440.     D0                         A0          A1   A2   D0      A3
  441.  
  442.     size_t CLTXT_ReplaceAll( struct Locale *, STRPTR, STRPTR, size_t,
  443.                              CLTXT_TokEntry * );
  444.  
  445.   FUNCTION
  446.     Replaces all cltext tokens occuring in src, result will
  447.     be put into dst.
  448.  
  449.   INPUTS
  450.     locale     -- locale to use (necessary for internal tokens)
  451.     src        -- source string
  452.     dst        -- destination buffer
  453.     dstlen     -- size of destination buffer
  454.     tokents    -- external token entries. This is an array
  455.                   terminated by an entry with a NULL name field.
  456.  
  457.   RESULT
  458.     len        -- length of resulting destination string
  459.  
  460.   EXAMPLE
  461.  
  462.   NOTES
  463.  
  464.   BUGS
  465.    None known.
  466.  
  467.   SEE ALSO
  468.     CLTXT_Replace()
  469.  
  470. cl_text.library/CLTXT_SPrintfA                 cl_text.library/CLTXT_SPrintfA
  471.  
  472.   NAME
  473.    CLTXT_SPrintfA -- sprintf()-like interface to FormatString() & ReplaceAll(
  474. )
  475.    CLTXT_SPrintf -- varargs stub
  476.  
  477.   SYNOPSIS
  478.    nextdata = CLTXT_SPrintfA( locale, buffer, format, args );
  479.    D0                           A0      A1      A2     A3
  480.  
  481.    APTR CLTXT_SprintfA( struct Locale *, STRPTR, STRPTR, APTR );
  482.    APTR CLTXT_SPrintf( struct Locale *, STRPTR, STRPTR, ... );
  483.  
  484.   FUNCTION
  485.    calls locale.library/FormatString() in a sprintf() like
  486.    manner. The resulting string will be processed by CLTXT_ReplaceAll().
  487.  
  488.   INPUTS
  489.    locale -- Locale to use. May be NULL.
  490.    buffer -- buffer to write to.
  491.    format -- formating string
  492.    args   -- args to format into string
  493.  
  494.   RESULT
  495.    nextdata -- points after last used element of args
  496.  
  497.   EXAMPLE
  498.  
  499.   NOTES
  500.  
  501.   BUGS
  502.    None known.
  503.  
  504.   SEE ALSO
  505.    locale.library/FormatString(), CLTXT_PrintfA()
  506.  
  507.